home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
c
/
matrx042.zip
/
MATRIX.DOC
< prev
next >
Wrap
Text File
|
1994-04-16
|
18KB
|
483 lines
/*
*-----------------------------------------------------------------------------
* file: matrix.doc
* desc: document for matrix toolbox function calls
* by: KO shu pui, patrick
* date: 24 may 92 v0.4
* 23 sep 93 v0.41
* 16 apr 94 v0.42
*-----------------------------------------------------------------------------
*/
===============================================================================
0. INTRODUCTION
===============================================================================
This document only provides you the following information:
0.1 How to create and free a matrix
0.2 Description of each matrix function call
0.3 Some hints to use this toolbox
Remember that this document will NOT describe the data structure and
any technical details of the toolbox - just because this document is
aimed at to be a sort-of "User's Guide" for programmers.
===============================================================================
1. OUR MATRIX OF REFERENCE
===============================================================================
In order to avoid terms confusion, here is our matrix of reference
(matrix A) which is of size m x n.
Column
Row 0 1 2 n-1
0 [ a0,0 a0,1 a0,2 ... a0,n-1 ]
A = 1 [ a1,0 a1,1 a1,2 ... a1,n-1 ]
2 [ a2,0 a2,1 a2,2 ... a2,n-1 ]
[ ... ... ... ... ... ]
m-1 [ am-1,0 am-1,1 am-1,2 ... am-1,n-1 ]
===============================================================================
2. BASIC MATRIX OBJECT OPERATION
===============================================================================
-------------------------------------------------------------------------------
Function : MATRIX mat_creat (int m, int n, int type)
Synopsis : creation of a matrix which can be used by the matrix toolbox
functions; memory is allocated for this object; and some
initialization is performed.
Parameter: m: number of rows
n: number of columns
type: matrix initialization type where
type=
UNDEFINED do not initialize the matrix
ZERO_MATRIX fill zero to all matrix elements
UNIT_MATRIX fill a one to all matrix element ai,j
where i=j
Return Value: the matrix object
Example:
MATRIX A;
/*
* create a 15 x 15 matrix;
* do not initialize the elements
*/
A = mat_creat( 15, 15, UNDEFINED);
/*
* put a 4 in element A(0,14) of matrix A,
* put a 2 in element A(3,5) of matrix A
*/
A[0][14] = 4.0;
A[3][5] = 2.0;
See Also: mat_free(), for Accessing a matrix, see this example.
-------------------------------------------------------------------------------
Function: MATRIX mat_fill ( MATRIX A, int type )
Synopsis: initialize a matrix will a simple type
Parameter: A: the matrix object for which mat_creat() has been called
type: matrix initialization type where
type=
UNDEFINED do not initialize the matrix
ZERO_MATRIX fill zero to all matrix elements
UNIT_MATRIX fill a one to all matrix element ai,j
where i=j
Return Value: MATRIX A
Example:
MATRIX A;
...
/*
* fill the matrix A will zeroes
*/
mat_fill( A, ZERO_MATRIX );
See Also: mat_creat()
-------------------------------------------------------------------------------
Function : int mat_free ( MATRIX A )
Synopsis : free all memory occupied by the matrix object A
Parameter: A: the matrix object for which mat_creat() was called
Return Value: None
Example:
MATRIX A;
A = mat_creat(...);
...
mat_free(A);
Note: since memory may be a very scarce resource in a computer,
as a C programmer you are advised to free up the matrix as
soon as that matrix will not be used any more in future.
See Also: mat_creat()
-------------------------------------------------------------------------------
Function: MatCol ( A )
Synopsis: find out the number of columns of a matrix object A
Parameter: A: the matrix object for which mat_creat() was called
Return Value: number of columns
Example:
int i;
...
i = MatCol(A);
Note: this is a macro
See Also: MatRow()
-------------------------------------------------------------------------------
Function: MatRow ( A )
Synopsis: find out the number of rows of a matrix object A
Parameter: A: the matrix object for which mat_creat() was called
Return Value: number of rows
Example:
int i;
...
i = MatRow(A);
Note: this is a macro
See Also: MatCol()
-------------------------------------------------------------------------------
Function: MATRIX mat_colcopy1 ( MATRIX A, MATRIX B, int j1, int j2 )
Synopsis: copy a column from a matrix A to a column at matrix B
Parameter: A, B: the matrix objects for which mat_creat() was called
column j1 of A is copied to column j2 of B;
Return Value: MATRIX A
Example:
MATRIX A, B;
A = mat_creat( 5, 4, ZERO_MATRIX );
B = mat_creat( 5, 4, UNDEFINED );
/*
* copy column 2 of A to column 0 of B
*/
mat_colcopy1( A, 2, B, 0 );
Note: the sizes of rows of A, B must be the same
See Also: mat_copy()
-------------------------------------------------------------------------------
Function: MATRIX mat_copy ( MATRIX A )
Synopsis: duplicate a matrix
Parameter: A: the matrix object for which mat_creat() was called
Return Value: Another allocated matrix object whose contents are same
as A
Example:
MATRIX A, B;
A = mat_creat( 5, 4, ZERO_MATRIX );
/*
* B is also a 5 x 4 zero matrix now
*/
B = mat_copy( A );
...
mat_free( B );
See Also: mat_colcopy1()
-------------------------------------------------------------------------------
===============================================================================
3. BASIC MATRIX OBJECT INPUT/OUTPUT OPERATION
===============================================================================
-------------------------------------------------------------------------------
Function: int fgetmat (MATRIX A, FILE * fp)
Synopsis: read a matrix from stream
Parameter: A: allocated matrix
fp: a stream pointer obtained from fopen() or predefined
pointer in standard library such as stdin
Return Value: number of matrix elements read
Example:
MATRIX A;
FILE *fp;
A = mat_creat(3, 3, UNDEFINED);
fp = fopen("mymatrix.dat", "r");
fgetmat( A, fp );
See Also: mat_dumpf(), mat_dump(), mat_fdump(), mat_fdumpf()
-------------------------------------------------------------------------------
Function: MATRIX mat_dump (MATRIX A)
MATRIX mat_dumpf (MATRIX A, char * format)